Crate opentelemetry

Implements the API component of OpenTelemetry.

Compiler support: requires rustc 1.64+

Getting Started

use opentelemetry::{global, trace::{TraceContextExt, Tracer}, Context };

fn do_something() {
    let tracer = global::tracer("my_component");
    let _guard = Context::current_with_span(tracer.start("my_span")).attach();
    // do work tracked by the now current span
}

See the examples directory for different integration patterns.

Traces

The trace module includes types for tracking the progression of a single request while it is handled by services that make up an application. A trace is a tree of Spans which are objects that represent the work being done by individual services or components involved in a request as it flows through a system.

Creating and exporting spans

use opentelemetry::{global, trace::{Span, Tracer}, KeyValue};

// get a tracer from a provider
let tracer = global::tracer("my_service");

// start a new span
let mut span = tracer.start("my_span");

// set some attributes
span.set_attribute(KeyValue::new("http.client_ip", "83.164.160.102"));

// perform some more work...

// end or drop the span to export
span.end();

See the trace module docs for more information on creating and managing spans.

Metrics

The metrics module includes types for recording measurements about a service at runtime.

Creating instruments and recording measurements

use opentelemetry::{global, KeyValue};

// get a meter from a provider
let meter = global::meter("my_service");

// create an instrument
let counter = meter.u64_counter("my_counter").init();

// record a measurement
counter.add(1, &[KeyValue::new("http.client_ip", "83.164.160.102")]);

See the metrics module docs for more information on creating and managing instruments.

Crate Feature Flags

The following core crate feature flags are available:

• trace: Includes the trace API (enabled by default).
• metrics: Includes the metrics API.
• logs: Includes the logs bridge API.

The following feature flags provides additional configuration for logs:

• logs_level_enabled: Allow users to control the log level

The following feature flags enable APIs defined in OpenTelemetry specification that is in experimental phase:

• otel_unstable: Includes unstable APIs (enabled by default).

Related Crates

In addition to opentelemetry, the open-telemetry/opentelemetry-rust repository contains several additional crates designed to be used with the opentelemetry ecosystem. This includes a collection of trace SpanExporter and metrics pull and push controller implementations, as well as utility and adapter crates to assist in propagating state and instrumenting applications.

In particular, the following crates are likely to be of interest:

• opentelemetry_sdk provides the SDK used to configure providers.
• opentelemetry-http provides an interface for injecting and extracting trace information from http headers.
• opentelemetry-jaeger provides a pipeline and exporter for sending trace information to Jaeger.
• opentelemetry-otlp exporter for sending trace and metric data in the OTLP format to the OpenTelemetry collector.
• opentelemetry-prometheus provides a pipeline and exporter for sending metrics information to Prometheus.
• opentelemetry-zipkin provides a pipeline and exporter for sending trace information to Zipkin.
• opentelemetry-datadog provides additional exporters to Datadog.
• opentelemetry-aws provides unofficial propagators for AWS X-ray.
• opentelemetry-contrib provides additional exporters and propagators that are experimental.
• opentelemetry-semantic-conventions provides standard names and semantic otel conventions.
• opentelemetry-stackdriver provides an exporter for Google’s Cloud Trace (which used to be called StackDriver).

Additionally, there are also several third-party crates which are not maintained by the opentelemetry project. These include:

• tracing-opentelemetry provides integration for applications instrumented using the tracing API and ecosystem.
• actix-web-opentelemetry provides integration for the actix-web web server and ecosystem.
• opentelemetry-application-insights provides an unofficial Azure Application Insights exporter.
• opentelemetry-tide provides integration for the Tide web server and ecosystem.

If you’re the maintainer of an opentelemetry ecosystem crate not listed above, please let us know! We’d love to add your project to the list!

Supported Rust Versions

OpenTelemetry is built against the latest stable release. The minimum supported version is 1.64. The current OpenTelemetry version is not guaranteed to build on Rust versions earlier than the minimum supported version.

The current stable Rust compiler and the three most recent minor versions before it will always be supported. For example, if the current stable compiler version is 1.49, the minimum supported version will not be increased past 1.46, three minor versions prior. Increasing the minimum supported compiler version is not considered a semver breaking change as long as doing so complies with this policy.

Modules

• baggage
  Primitives for sending name/value data across system boundaries.
• global
  Utilities for working with global telemetry primitives
• logslogs
  OpenTelemetry Logs Bridge API
• metricsmetrics
  OpenTelemetry Metrics API
• propagation
  OpenTelemetry Propagator interface
• tracetrace
  API for tracing applications and libraries.

Structs

• Context
  An execution-scoped collection of values.
• ContextGuard
  A guard that resets the current context to the prior context when dropped.
• InstrumentationLibrary
  Information about a library or crate providing instrumentation.
• Key
  The key part of attribute KeyValue pairs.
• KeyValue
  A key-value pair describing an attribute.
• StringValue
  Wrapper for string-like values

Enums

• Array
  A Value::Array containing homogeneous values.
• Value
  The value part of attribute KeyValue pairs.

Traits

• ExportError
  Marker trait for errors returned by exporters